[xtask] Add aggro subcommand for building aggregate docs#2481
[xtask] Add aggro subcommand for building aggregate docs#2481jamesmunns wants to merge 9 commits intomasterfrom
aggro subcommand for building aggregate docs#2481Conversation
not worth it for now.
|
Thing to add: UDP sockets by task + port |
| pub fn run(app_toml: &Path, output: Option<&Path>) -> Result<()> { | ||
| let cfg = Config::from_file(app_toml)?; | ||
|
|
||
| println!("{}", std::env::current_dir().unwrap().display()); |
| // Exactly one match | ||
| [found] => Some(found.clone()), | ||
| _ => { | ||
| panic!("too many readmes"); |
There was a problem hiding this comment.
I've vote to log an error (including the task name) and continue instead of panicking, on the rare chance that a task has both readme.md and readme.mkdn.
| writeln!(&mut mkdn)?; | ||
| writeln!( | ||
| &mut mkdn, | ||
| "| task: crate | priority | stack (bytes) | interrupts | client of | server for |" |
There was a problem hiding this comment.
I find "client of" / "server for" confusing, maybe "called by" and "calls into"?
| let stack = if let Some(amt) = task.stacksize { | ||
| amt.to_string() | ||
| } else { | ||
| "???".to_string() |
There was a problem hiding this comment.
Use cfg.stacksize as fallback before declaring defeat here.
| // | ||
| // Write this as markdown for laziness, then HTMLify it | ||
| let mut mkdn = String::new(); | ||
| writeln!(&mut mkdn, "# `{}` docs", task.name)?; |
There was a problem hiding this comment.
Let's remove this, since it just adds busyness to the page.
| let mut mkdn = String::new(); | ||
| writeln!(&mut mkdn, "# `{}` docs", task.name)?; | ||
| writeln!(&mut mkdn)?; | ||
| writeln!(&mut mkdn, "(this page intentionally left blank)")?; |
There was a problem hiding this comment.
| writeln!(&mut mkdn, "(this page intentionally left blank)")?; | |
| writeln!(&mut mkdn, "(no README available)")?; |
to make it more clear what's going on
| } => { | ||
| if !dest_url.starts_with("http") { | ||
| // TODO: rewrite relative to `https://github.com/oxidecomputer/hubris/blob/master/`? | ||
| // use _base to figure out relative paths, we might also need to |
| /// Generate a directed graph of task priorities and task_slot | ||
| /// dependencies. | ||
| pub fn task_graph(app_toml: &Path, path: &Path) -> Result<()> { | ||
| let dot = File::create(path)?; |
There was a problem hiding this comment.
Is this prep for including the graph in the docs? I don't see it used anywhere.
| pub app_config: String, | ||
| pub auxflash: Option<AuxFlashData>, | ||
| pub caboose: Option<CabooseConfig>, | ||
| pub docfile: Option<PathBuf>, |
There was a problem hiding this comment.
No one is using this yet, right?
There was a problem hiding this comment.
Ah, I see it's just Cosmo right now.
| } => { | ||
| if !dest_url.starts_with("http") { | ||
| // TODO: rewrite relative to `https://github.com/oxidecomputer/hubris/blob/master/`? | ||
| // use _base to figure out relative paths, we might also need to |
| id, | ||
| }) | ||
| } | ||
| // Bump down headings one notch, to allow for top level docs |
There was a problem hiding this comment.
Weirdly, I still see h1 headings for tasks in your sample file:
| buf: &mut String, | ||
| ) -> Result<()> { | ||
| let mut mkdn = String::new(); | ||
| writeln!(&mut mkdn, "# Task: \"{name}\" (`{}`)", task.name)?; |
There was a problem hiding this comment.
vibes:
| writeln!(&mut mkdn, "# Task: \"{name}\" (`{}`)", task.name)?; | |
| writeln!(&mut mkdn, "# `{name}` (`{}`)", task.name)?; |
The task name is also used as an identifier in code, and I think it's overkill for the header to tell us it's a task.
| let parser = pulldown_cmark::Parser::new_ext(&mkdn, PULLDOWN_OPTS); | ||
| html::push_html(buf, parser); | ||
|
|
||
| if let Some(readme) = cfg.docfile.as_ref() { |
There was a problem hiding this comment.
Should we try to find a README if this is empty, based on Cargo metadata?
(I'm fine with this being a later PR)
2 participants
I've currently plumbed a good "base coat" of the
aggrosubcommand (name bikeshedding welcome, it was funny on a Friday morning), which generally:Currently, it looks like this:
aggro.html
From now, there are a couple of questions:
mdbook?I did try figuring out how to insert the task graph, sadly the
launch-rscrate isn't as good at layouting as thedotbin is, and neither are great for making legible diagrams. We may want to break this up on a per-task basis just to reduce the number of entities per-graph.